Languguage OS 2/Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO/gnu/elispman.lha/elispman/markers.texi

Lisp/Scheme | 1993-05-20 | 19KB | 580 lines

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/markers
@node Markers, Text, Positions, Top
@chapter Markers
@cindex markers

  A @dfn{marker} is a Lisp object used to specify a position in a buffer
relative to the surrounding text.  A marker changes its offset from the
beginning of the buffer automatically whenever text is inserted or
deleted, so that it stays with the two characters on either side of it.

@menu
* Overview of Markers::      The components of a marker, and how it relocates.
* Predicates on Markers::    Testing whether an object is a marker.
* Creating Markers::         Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character position.
* Changing Markers::         Moving the marker to a new buffer or position.
* The Mark::                 How ``the mark'' is implemented with a marker.
* The Region::               How to access ``the region''.
@end menu

@node Overview of Markers, Predicates on Markers, Markers, Markers
@section Overview of Markers

  A marker specifies a buffer and a position in that buffer.  The marker
can be used to represent a position in the functions that require one,
just as an integer could be used.  @xref{Positions}, for a complete
description of positions.

  A marker has two attributes: the marker position, and the marker
buffer.  The marker position is an integer which is equivalent (at the
moment) to the marker as a position in that buffer; however, as text is
inserted or deleted in the buffer, the marker is relocated, so that its
integer equivalent changes.  The idea is that a marker positioned
between two characters in a buffer will remain between those two
characters despite any changes made to the contents of the buffer; thus,
a marker's offset from the beginning of a buffer may change often during
the life of the marker.

@cindex marker relocation
  If the text around a marker is deleted, the marker is repositioned
between the characters immediately before and after the deleted text.  If
text is inserted at the position of a marker, the marker remains in front
of the new text unless it is inserted with @code{insert-before-markers}
(@pxref{Insertion}).  When text is inserted or deleted somewhere before the
marker position (not next to the marker), the marker moves back and forth
with the two neighboring characters.

@cindex marker garbage collection
  When a buffer is modified, all of its markers must be checked so that
they can be relocated if necessary.  This slows processing in a buffer
with a large number of markers.  For this reason, it is a good idea to
make a marker point nowhere if you are sure you don't need it any more.
Unreferenced markers will eventually be garbage collected, but until
then will continue to be updated if they do point somewhere.

@cindex markers as numbers
  Because it is quite common to perform arithmetic operations on a marker
position, most of the arithmetic operations (including @code{+} and
@code{-}) accept markers as arguments.  In such cases, the current position
of the marker is used.

Here are examples of creating markers, setting markers, and moving point
to markers:

@example
@group
;; @r{Make a new marker that initially does not point anywhere:}
(setq m1 (make-marker))
     @result{} #<marker in no buffer>
@end group

@group
;; @r{Set @code{m1} to point between the 100th and 101st characters}
;;   @r{in the current buffer:}
(set-marker m1 100)
     @result{} #<marker at 100 in markers.texi>
@end group

@group
;; @r{Now insert one character at the beginning of the buffer:}
(goto-char (point-min))
     @result{} 1
(insert "Q")
     @result{} nil
@end group

@group
;; @r{@code{m1} is updated appropriately.}
m1
     @result{} #<marker at 101 in markers.texi>
@end group

@group
;; @r{Two markers that point to the same position}
;;   @r{are not @code{eq}, but they are @code{equal}.}
(setq m2 (copy-marker m1))
     @result{} #<marker at 101 in markers.texi>
(eq m1 m2)
     @result{} nil
(equal m1 m2)
     @result{} t
@end group

@group
;; @r{When you are finished using a marker, make it point nowhere.}
(set-marker m1 nil)
     @result{} #<marker in no buffer>
@end group
@end example

@node Predicates on Markers, Creating Markers, Overview of Markers, Markers
@section Predicates on Markers

  You can test an object to see whether it is a marker, or whether it is
either an integer or a marker.  The latter test is useful when you are
using the arithmetic functions that work with both markers and integers.

@defun markerp object
  This function returns @code{t} if @var{object} is a marker,
@code{nil} otherwise.  In particular, integers are not markers,
even though many functions will accept either a marker or an
integer.
@end defun

@defun integer-or-marker-p object
  This function returns @code{t} if @var{object} is an integer or a marker,
@code{nil} otherwise.
@end defun

@defun number-or-marker-p object
  This function returns @code{t} if @var{object} is a number (of any
type) or a marker, @code{nil} otherwise.
@end defun

@node Creating Markers, Information from Markers, Predicates on Markers, Markers
@section Functions That Create Markers

  When you create a new marker, you can make it point nowhere, or point
to the present position of point, or to the beginning or end of the
accessible portion of the buffer, or to the same place as another given
marker.

@defun make-marker
  This functions returns a newly allocated marker that does not point
anywhere.

@example
@group
(make-marker)
     @result{} #<marker in no buffer>
@end group
@end example
@end defun

@defun point-marker
  This function returns a new marker that points to the present position
of point in the current buffer.  @xref{Point}.  For an example, see
@code{copy-marker}, below.
@end defun

@defun point-min-marker
  This function returns a new marker that points to the beginning of the
accessible portion of the buffer.  This will be the beginning of the
buffer unless narrowing is in effect.  @xref{Narrowing}.
@end defun

@defun point-max-marker
@cindex end of buffer marker
  This function returns a new marker that points to the end of the
accessible portion of the buffer.  This will be the end of the buffer
unless narrowing is in effect.  @xref{Narrowing}.

Here are examples of this function and @code{point-min-marker}, shown in
a buffer containing a version of the source file for the text of this
chapter.

@example
@group
(point-min-marker)
     @result{} #<marker at 1 in markers.texi>
(point-max-marker)
     @result{} #<marker at 15573 in markers.texi>
@end group

@group
(narrow-to-region 100 200)
     @result{} nil
@end group
@group
(point-min-marker)
     @result{} #<marker at 100 in markers.texi>
@end group
@group
(point-max-marker)
     @result{} #<marker at 200 in markers.texi>
@end group
@end example
@end defun

@defun copy-marker marker-or-integer
  If passed a marker as its argument, @code{copy-marker} returns a
new marker that points to the same place and the same buffer as does
@var{marker-or-integer}.  If passed an integer as its argument,
@code{copy-marker} returns a new marker that points to position
@var{marker-or-integer} in the current buffer.

  If passed an argument that is an integer whose value is less than 1,
@code{copy-marker} returns a new marker that points to the
beginning of the current buffer.  If passed an argument that is an
integer whose value is greater than the length of the buffer, then
@code{copy-marker} returns a new marker that points to the end of the
buffer.

  An error is signaled if @var{marker} is neither a marker nor an
integer.

@example
@group
(setq p (point-marker))
     @result{} #<marker at 2139 in markers.texi>
@end group

@group
(setq q (copy-marker p))
     @result{} #<marker at 2139 in markers.texi>
@end group

@group
(eq p q)
     @result{} nil
@end group

@group
(equal p q)
     @result{} t
@end group

@group
(copy-marker 0)
     @result{} #<marker at 1 in markers.texi>
@end group

@group
(copy-marker 20000)
     @result{} #<marker at 7572 in markers.texi>
@end group
@end example
@end defun

@node Information from Markers, Changing Markers, Creating Markers, Markers
@section Information from Markers

  This section describes the functions for accessing the components of a
marker object.

@defun marker-position marker
  This function returns the position that @var{marker} points to, or
@code{nil} if it points nowhere.
@end defun

@defun marker-buffer marker
  This function returns the buffer that @var{marker} points into, or
@code{nil} if it points nowhere.

@example
@group
(setq m (make-marker))
     @result{} #<marker in no buffer>
@end group
@group
(marker-position m)
     @result{} nil
@end group
@group
(marker-buffer m)
     @result{} nil
@end group

@group
(set-marker m 3770 (current-buffer))
     @result{} #<marker at 3770 in markers.texi>
@end group
@group
(marker-buffer m)
     @result{} #<buffer markers.texi>
@end group
@group
(marker-position m)
     @result{} 3770
@end group
@end example
@end defun

  Two distinct markers will be found @code{equal} (even though not
@code{eq}) to each other if they have the same position and buffer, or
if they both point nowhere.

@node Changing Markers, The Mark, Information from Markers, Markers
@section Changing Markers

  This section describes how to change the position of an existing
marker.  When you do this, be sure you know whether the marker is used
outside of your program, and, if so, what effects will result from
moving it---otherwise, confusing things may happen in other parts of
Emacs.

@defun set-marker marker position &optional buffer
  This function moves @var{marker} to @var{position}
in @var{buffer}.  If @var{buffer} is not provided, it defaults to
the current buffer.

  If @var{position} is less than 1, @code{set-marker} moves marker to
the beginning of the buffer.  If the value of @var{position} is greater
than the size of the buffer, @code{set-marker} moves marker to the end
of the buffer.  If @var{position} is @code{nil} or a marker that points
nowhere, then @var{marker} is set to point nowhere.

  The value returned is @var{marker}.

@example
@group
(setq m (point-marker))
     @result{} #<marker at 4714 in markers.texi>
@end group
@group
(set-marker m 55)
     @result{} #<marker at 55 in markers.texi>
@end group
@group
(setq b (get-buffer "foo"))
     @result{} #<buffer foo>
@end group
@group
(set-marker m 0 b)
     @result{} #<marker at 1 in foo>
@end group
@end example
@end defun

@defun move-marker marker position &optional buffer
  This is another name for @code{set-marker}.
@end defun

@node The Mark, The Region, Changing Markers, Markers
@section The Mark
@cindex mark, the
@cindex mark ring

  A special marker in each buffer is designated @dfn{the mark}.  It
records a position for the user for the sake of commands such as
@kbd{C-w} and @kbd{C-x @key{TAB}}.  Lisp programs should set the mark
only to values that have a potential use to the user, and never for
their own internal purposes.  For example, the @code{replace-regexp}
command sets the mark to the value of point before doing any
replacements, because this enables the user to move back there
conveniently after the replace is finished.

  Many commands are designed so that when called interactively they
operate on the text between point and the mark.  If you are writing such
a command, don't examine the mark directly; instead, use
@code{interactive} with the @samp{r} specification.  This will provide
the values of point and the mark as arguments to the command in an
interactive call, but will permit other Lisp programs to specify
arguments explicitly.  @xref{Interactive Codes}.

  Each buffer has its own value of the mark that is independent of the
value of the mark in other buffers.  When a buffer is created, the mark
exists but does not point anywhere.  We consider this state as ``the
absence of a mark in that buffer''.

  Once the mark ``exists'' in a buffer, it normally never ceases to
exist.  However, it may become @dfn{inactive}, if Transient Mark mode is
enabled.  The variable @code{mark-active}, which is always local in all
buffers, indicates whether the mark is active: non-@code{nil} means
yes.  A command can request deactivation of the mark upon return to the
editor command loop by setting @code{deactivate-mark} to a
non-@code{nil} value (but this deactivation only follows if Transient
Mark mode is enabled).

  The main motivation for using Transient Mark mode is that this mode
also enables highlighting of the region when the mark is active.
@xref{Emacs Display}.

  In addition to the mark, each buffer has a @dfn{mark ring} which is a
list of markers that are the previous values of the mark.  When editing
commands change the mark, they should normally save the old value of the
mark on the mark ring.  The mark ring may contain no more than the
maximum number of entries specified by the variable @code{mark-ring-max};
excess entries are discarded on a first-in-first-out basis.

@defun mark &optional force
@cindex current buffer mark
  This function returns the position of the current buffer's mark as an
integer.

Normally, if the mark is inactive @code{mark} signals an error.
However, if @var{force} is non-@code{nil}, then it returns the mark
position anyway---or @code{nil}, if the mark is not yet set for this
buffer.
@end defun

@defun mark-marker
  This function returns the current buffer's mark.  This is the very marker
which records the mark location inside Emacs, not a copy.  Therefore,
changing this marker's position will directly affect the position of the mark.
Don't do it unless that is the effect you want.

@example
@group
(setq m (mark-marker))
     @result{} #<marker at 3420 in markers.texi>
@end group
@group
(set-marker m 100)
     @result{} #<marker at 100 in markers.texi>
@end group
@group
(mark-marker)
     @result{} #<marker at 100 in markers.texi>
@end group
@end example

Like any marker, this marker can be set to point at any buffer you like.
We don't recommend that you make it point at any buffer other than the
one of which it is the mark.  If you do, it will yield perfectly
consistent, if rather odd, results.
@end defun

@ignore
@deffn Command set-mark-command jump
  If @var{jump} is @code{nil}, this command sets the mark to the value
of point and pushes the previous value of the mark on the mark ring.  The
message @samp{Mark set} is also displayed in the echo area.

  If @var{jump} is not @code{nil}, this command sets point to the value
of the mark, and sets the mark to the previous saved mark value, which
is popped off the mark ring.

  This function is @emph{only} intended for interactive use.
@end deffn
@end ignore

@defun set-mark position
  This function sets the mark to @var{position}, and activates the mark.
The old value of the mark is @emph{not} pushed onto the mark ring.

  @strong{Please note:} use this function only if you want the user to
see that the mark has moved, and you want the previous mark position to
be lost.  Normally, when a new mark is set, the old one should go on the
@code{mark-ring}.  For this reason, most applications should use
@code{push-mark} and @code{pop-mark}, not @code{set-mark}.

  Novice Emacs Lisp programmers often try to use the mark for the wrong
purposes.  The mark saves a location for the user's convenience.  An
editing command should not alter the mark unless altering the mark is
part of the user-level functionality of the command.  (And, in that
case, this effect should be documented.)  To remember a location for
internal use in the Lisp program, store it in a Lisp variable.  For
example:

@example
@group
(let ((beg (point)))
  (forward-line 1)
  (delete-region beg (point))).
@end group
@end example
@end defun

@c for interactive use only
@ignore
@deffn Command exchange-point-and-mark
  This function exchanges the positions of point and the mark.
It is intended for interactive use.
@end deffn
@end ignore

@defvar mark-ring
  The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.

@example
@group
mark-ring
@result{} (#<marker at 11050 in markers.texi>
    #<marker at 10832 in markers.texi>
    @dots{})
@end group
@end example
@end defvar

@defopt mark-ring-max
The value of this variable is the maximum size of @code{mark-ring}.
If more marks than this are pushed onto the @code{mark-ring}, it
discards marks on a first-in, first-out basis.
@end defopt

@defun push-mark &optional position nomsg activate
This function sets the current buffer's mark to @var{position}, and
pushes a copy of the previous mark onto @code{mark-ring}.  If
@var{position} is @code{nil}, then the value of point is used.
@code{push-mark} returns @code{nil}.

The function @code{push-mark} normally @emph{does not} activate the
mark.  To do that, specify @code{t} for the argument @var{activate}.

A @samp{Mark set} message is displayed unless @var{nomsg} is
non-@code{nil}.
@end defun

@defun pop-mark
This function pops off the top element of @code{mark-ring} and makes
that mark become the buffer's actual mark.  This does not change the
buffer's point, and does nothing if @code{mark-ring} is empty.  It
deactivates the mark.

The return value is not useful.
@end defun

@defopt transient-mark-mode
@cindex Transient Mark mode
This variable enables Transient Mark mode, in which every
buffer-modifying primitive sets @code{deactivate-mark}.  The consequence
of this is that commands that modify the buffer normally cause the mark
to become inactive.
@end defopt

@defvar deactivate-mark
If an editor command sets this variable non-@code{nil}, then the editor
command loop deactivates the mark after the command returns.
@end defvar

@defvar mark-active
The mark is active when this variable is non-@code{nil}.  This variable
is always local in each buffer.
@end defvar

@defvar activate-mark-hook
@defvarx deactivate-mark-hook
These normal hooks are run, respectively, when the mark becomes active
and when it becomes inactive.  The hook @code{activate-mark-hook} is also
run at the end of a command if the mark is active and the region may
have changed.
@end defvar

@node The Region,  , The Mark, Markers
@section The Region
@cindex region, the

  The text between point and the mark is known as @dfn{the region}.
Various functions operate on text delimited by point and the mark, but
only those functions specifically related to the region itself are
described here.

@defun region-beginning
  This function returns the position of the beginning of the region (as
an integer).  This is the position of either point or the mark,
whichever is smaller.

  If the mark does not point anywhere, an error is signaled.
@end defun

@defun region-end
  This function returns the position of the end of the region (as an
integer).  This is the position of either point or the mark, whichever is
larger.

  If the mark does not point anywhere, an error is signaled.
@end defun

  Few programs need to use the @code{region-beginning} and
@code{region-end} functions.  A command designed to operate on a region
should instead use @code{interactive} with the @samp{r} specification,
so that the same function can be called with explicit bounds arguments
from programs.  (@xref{Interactive Codes}.)